<!DOCTYPE html> 
<!--
 Copyright (c) 2010 - 2018 TU Wien ACIN, fortiss GmbH
               2018 - 2019 Andrea Zoitl, Johannes Kepler University Linz
               2018		   Jan Holzweber
  
 This program and the accompanying materials are made available under the
 terms of the Eclipse Public License 2.0 which is available at
 http://www.eclipse.org/legal/epl-2.0.

 SPDX-License-Identifier: EPL-2.0
 
 Contributors:
   Carolyn Oates, Monika Wenger, Jose Cabral 
     - initial API and implementation and/or initial documentation
   Andrea Zoitl - cleaning up tutorials for 1.10 release, updated ToC
   Bianca Wiesmayr - minor text corrections
   Jan Holzweber - added tutorial Step 7
-->

<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>Step 4 - Create Your own Function Block Types</title>
    <link rel="stylesheet" type="text/css" href="../help.css" />
  </head>
  <body>

<!--********************************************************************************************-->
    
<h1 id="topOfPage">Step 4 - Create Your own Function Block Types</h1>

<p>This page is part of a guide that gives a walk-through of the major 4diac&nbsp;IDE features.</p>

    <ol start="0">
      <li><a href="../../html/4diacIDE/overview.html">4diac IDE Overview</a></li>
      <li><a href="../../html/4diacIDE/use4diacLocally.html">Use 4diac Locally (Blinking tutorial)</a></li>
      <li><a href="../../html/4diacIDE/distribute4diac.html">Distribute 4diac Applications</a></li>
      <li><a href="../../html/4diacIDE/use4diacRemotely.html">Deploy Applications Remotely</a></li>
      <li>Create Your own Function Block Types (YOU ARE HERE!)</li>
      <li><a href="../../html/4diacIDE/otherUseful.html">Other Basic Features</a></li>
      <li><a href="../../html/4diacIDE/advancedFeatures.html">Advanced Features</a></li>
      <li><a href="../../html/4diacIDE/dynamicTypeLoader.html">Deploying new FBs with the Dynamic Type Loader</a></li>
    </ol>

<p>In this tutorial, you will learn how to create your own Function Block (FB).
There are several different types of Function Blocks, we will show how to create a Basic, a Simple, a Composite and a Service Function Block. 
The new FBs are then available in the FB Palette for use in the Applications of the System.</p>

<p>New FBs need to be created when the desired functionality doesn't exist as a library FB or multiple FBs should be combined into just one FB. 
First, you have to define the interface with its input and output events and data. 
Afterwards, define the FB internals, which are defined by the kind of FB. </p>

<p>We implement the Blinking functionality inside all three different FB types to introduce their creation process.
All four types do the same thing in different ways.
At an event input, the Boolean data output will be toggled and the event output will message that the value has changed.</p>

<p>Create a new Function Block by selecting: 
	<br><b><span class="button4diac">File &rarr; New &rarr; New Type</span></b></p>

<!--********************************************************************************************-->

<h2 id="createBasic">Create a Basic Function Block</h2>

<p>Follow the instructions in the creation wizard. 
For this tutorial, select BlinkTest as the parent folder. Choose a name for the new FB, we name it <i>BasicTest</i>. 
Afterwards, select the type of FB you want to create, in this case we choose <i>Basic</i>.
The <b>Function Block Type Editor (FBT Editor)</b> opens after clicking Finish.</p>

<img src="../../html/4diacIDE/img/Step4/newTypeWizardBasic.png" alt="New Type Wizard - Create a Basic Function Block" />

<ol>
	<li>Your newly created type appears in the Type Library of your System BlinkTest.</li>
	<li>The central editing area shows the FB part you are currently working on. 
	Initially, it shows the interface of the Function Block.</li>
	<li>The Palette shows all elements you can add to the FB interface.</li>
	<li>The tabs below the central editing area identify the current part of the Function Block you're editing. 
	The picture shows the selected Interface tab.</li>
	<li>The properties below show the information about the Function Block.</li>
</ol>

<img src="../../html/4diacIDE/img/Step4/typeBasicGeneral.png" alt="General View after Creating a Basic Function Block" />

<!--********************-->
<h3 id="changeInterface">Change the Interface</h3>

<p>The Basic FB already has some inputs and outputs which are commonly used.
If you need another, just drag and drop it from the Palette into the FB or right-click at the FB to set another input or output.
Of course you can also delete them by pressing the Delete key or right-click &rarr; Delete.</p>

<p>In this example, we are doing a Blinking Function Block. 
This should have then one input event that triggers the change, one output event as an indicator of a change, and a Boolean data output for the state.
<br>By default, the Boolean output is set to <i>false</i> and remembers the state until a new event comes in and converts the Boolean to <i>true</i> until the next input arrives.
<br>Right now, the Basic FB has more inputs and outputs than we need.</p>

<ol>
	<li>Select the INIT event, and delete it. Do the same for QI and INITO.</li>
	<li>Select the QO output, and change its name to STATE by either double-clicking on it, or in the Properties below. 
		You can change the Comment for each event and data also in the Properties.</li>
	<li>Check that the Type of STATE is BOOL in Properties.</li>
	<li>Check the lines between events and data which represent the WITH. 
	    They indicate which data outputs are refreshed when an Event occurs. 
	    Similarly work event and data inputs, but in this case there's no data input to refresh. 
	    Since the STATE is changed when CNF is triggered, there's a WITH line between them.</li>
	<li>Try and add Events and different types of Data input and outputs to the interface to play around from the Palette. 
	    Finally, leave it again as in the image.</li>
</ol>

<img src="../../html/4diacIDE/img/Step4/createBasicInterface.png" alt="Create Basic Type - Interface"/>

<!--********************-->
<h3 id="changeECC">Change the ECC</h3>

<p>Select the <b>ECC (Execution Control Chart) tab</b> at the bottom of the central editing area, and you will see a state machine graph. 
This is the default one, and here's where you actually code the behavior of the Function Block. 
Purple boxes are states (the initial one is double-framed), the yellow ones represent the Algorithms that are executed when the Function Block enters the state, and the green ones are the triggered events after the algorithm. 
The arrows between them represent Events that arrive at the Function Block. 
Conditions are assigned to these arrows. 
A "1" means that it will always change state after the algorithm. 
Events are consumed only one at a time. The small numbers at the beginning of the transition are the priorities, in case more than one transition is possible. 
Don't try to understand everything at once. With a little practice, the terms and concepts become clearer.</p>

<ol>
	<li>Select and delete everything (Click and Drag) but the <i>START</i> state.</li>
	<li>Add a State from the Palette on the right by Drag and Drop from the Palette. 
	    Change its name to <i>On</i> by either double-clicking on it, or selecting and then editing the Properties below.
		</li>
	<li>Add another State and name it <i>Off</i>.</li>
	<li>Add an Action to the state <i>On</i> via Drag and Drop from the Palette or right click &rarr; Add Action.</li>
	<li>Select nothing by clicking in the background of the central editing area, then select the Algorithms tab in Property view. 
	    Here you see all the default algorithms of the Function Block. 
	    Delete them all by selecting and clicking the red cross, since we don't use them in this example.</li>
	<li>Add one algorithm by clicking on the green plus. Select the name and change it to <i>turnOn</i>. 
	    <br>Depending on the selected algorithm type, different algorithm editors are provided. 
	    Currently, the most used algorithm language is IEC 61131-3 Structured Text (ST). The ST Editor provides syntax highlighting and code completion. 
	    We'll see later that this code is converted to 4diac FORTE code. 
		If you select AnyText, no conversion is done, so you should know the syntax for 4diac FORTE (or other runtime environment).
		<p>On the right side, you can write your code.
	    As the name implies, in the <i>turnOn</i> algorithm we set your STATE variable to TRUE.
	    Using the name of the Data Output (or input or internal variable), you access its value for reading and writing.</p>
	    <div class="code">STATE := TRUE;</div> 
	    <br><img src="../../html/4diacIDE/img/Step4/addAlgorithm.png" alt="Add an Algorithm to the Action"/></li>
	<li>Double-click on the yellow box of the action of the <i>On</i> state and select the <i>turnOn</i> algorithm. 
	    Alternatively, you can also select this in the Property view.</li>
	<li>Double-click on the green box of the action of the <i>On</i> state and select the <i>CNF</i> output event. 
	    Alternatively, you can also select this in the Property view.</li>
	<li>Add another algorithm by clicking on the green plus. Select the name and change it to <i>turnOff</i>. 
	    As the name implies, in the <i>turnOff</i> algorithm we set your STATE variable to FALSE.
	    <div class="code">STATE := FALSE;</div></li>
	<li>Double-click on the yellow box of the action of the <i>Off</i> state and select the <i>turnOff</i> algorithm.</li>
	<li>Double-click on the green box of the action of the <i>Off</i> state and select the <i>CNF</i> output event.
	    <br><img src="../../html/4diacIDE/img/Step4/stateAndActions.png" alt="Current score of the States And Actions"/></li>
	<li>Draw a transition via Drag and Drop from the <i>START</i> to the state <i>On</i>. 
	Select it, and in the transition tab of the Properties view select the condition <i>REQ</i>.
	Next to it, you have the possibility to add a condition (for example, if STATE == TRUE or similar). 
	In this example, no condition except the <i>REQ</i> event is needed.</li>
	<li>Draw a transition by Drag and Drop from the state <i>On</i> to the state <i>Off</i>. 
	Select it, and in the transition tab of the Properties view select the condition <i>REQ</i>.</li>
	<li>Draw a transition by Drag and Drop from the state <i>Off</i> to the state <i>On</i>. 
	Select it, and in the transition tab of the Properties view select the condition <i>REQ</i>.</li>
</ol>

<img src="../../html/4diacIDE/img/Step4/createBasicECC.png" alt="Basic ECC example">

<p>At the beginning, the FB is in the START state. 
When a REQ event arrives, it jumps to the <i>On</i> state, executes algorithm <i>turnOn</i> and triggers the <i>CNF</i> output event.
When the next event arrives, it jumps to <i>Off</i> state, executes algorithm <i>turnOff</i> and triggers the <i>CNF</i> output event.
   That's how the ECC works.</p>

<p>In case the transition with a "1" had also a REQ event, an infinite loop won't happen since the event is consumed only once. 
   You would need to REQ events to go back.</p>

<p><a href="#exportTypes">Exporting</a> the Function Block and <a href="#testFunctionBlock">testing</a> are presented after the chapter Create a <a href="#createComposite">Composite</a> and <a href="#createService">Service</a> Function Block.</p>

<!--********************************************************************************************-->

<h2 id="createSimple">Create a Simple Function Block</h2>

<p>The Simple FB has only one algorithm and no ECC.</p>

<p>Create a new Type by following the instructions in the creation wizard. 
For this tutorial, select BlinkTest as the parent folder. Choose a name for the new FB, we name it <i>SimpleTest</i>. 
Afterwards, select the type of FB you want to create, in this case we choose <i>Simple</i>.
The <i>Function Block Type Editor (FBT Editor)</i> is opening after clicking Finish.</p>

<img src="../../html/4diacIDE/img/Step4/newTypeWizardSimple.png" alt="New Type Wizard - Create a Simple Function Block" />

<ol>
	<li>Change the interface as <a href="#changeInterface">before</a>.
	<br><img src="../../html/4diacIDE/img/Step4/createSimpleInterface.png" alt="Create Simple Type - Interface"/></li>
	<li>Select the <b>Algorithm tab</b> at the bottom of the central editing area. In this view, you can define an algorithm of the Simple FB. 
		<div><img src="../../html/4diacIDE/img/Step4/createSimpleFBAlgorithm.png" alt="Simple FB Algorithm example"></div></li>
</ol>

<p>That's all you need to do for the Simple Function Block.</p>

<!--********************************************************************************************-->

<h2 id="createComposite">Create a Composite Function Block</h2>

<p>Create a new Type following the instructions in the creation wizard. 
For this tutorial, select BlinkTest as the parent folder. Choose a name for the new FB, we name it <i>CompositeTest</i>. 
Afterwards, select the type of FB you want to create, in this case we choose <i>Composite</i>.
The <i>Function Block Type Editor (FBT Editor)</i> is opening after clicking Finish.</p>

<img src="../../html/4diacIDE/img/Step4/newTypeWizardComposite.png" alt="New Type Wizard - Create a Composite Function Block" />

<ol>
	<li>Change the interface as <a href="#changeInterface">before</a>.
	<br><img src="../../html/4diacIDE/img/Step4/createCompositeInterface.png" alt="Create Composite Type - Interface"/></li>
	<li>Select the <b>Composite Network tab</b> at the bottom of the central editing area. 
	    In this view, you can create your own network of FBs inside the Function Block. 
	    For this example, use the E_SWITCH and E_SR and connect them as in the original Blink example.</li>
	<li>On the edges of the central editing area, you can see events and data that correspond to the interface of the Composite. 
	    Connect them as in the image below.
		<div><img src="../../html/4diacIDE/img/Step4/createCompositeNetwork.png" alt="Composite Network example"></div></li>
</ol>

<p>That's all you need to do for the Composite Function Block.</p>

<!--********************************************************************************************-->

<h2 id="createService">Create a Service Function Block</h2>

<p>Create a new Type by following the instructions in the creation wizard. 
For this tutorial, select BlinkTest as the parent folder. Choose a name for the new FB, we name it <i>ServiceInterfaceTest</i>. 
Select then the type of FB you want to create, in this case we choose <i>Service Interface</i>.
The <i>Function Block Type Editor (FBT Editor)</i> opens after clicking Finish.</p>
   
   <img src="../../html/4diacIDE/img/Step4/newTypeWizardServiceInterface.png" alt="New Type Wizard - Create a Service Interface Function Block" />

<p>Change the interface as <a href="#changeInterface">before</a>.</p>
<br><img src="../../html/4diacIDE/img/Step4/createServiceInterfaceInterface.png" alt="Create Service Interface Type - Interface"/>

<p>That's it. The behavior of the Service Function Block must be implemented directly in the code that's generated from it. 
You will need to implement the functionality for each incoming event, manage the internal variables and send output events by yourself after exporting. <a href="#finishService">Below</a>, you find the code for this example.</p>

<!--********************************************************************************************-->

<h2 id="exportTypes">Export Function Block Types</h2>

<p>4diac IDE provides an export filter to generate C++ code which can be included in the 4diac&nbsp;FORTE development process. 
In order to export a Function Block Type, either</p>

<ul>
	<li>select File &rarr; Export &rarr; 4diac&nbsp;IDE &rarr; 4diac&nbsp;IDE Type Export &rarr; Next</li>
	<li>right-click on the Function Block to export and select Export &rarr; 4diac&nbsp;IDE &rarr; 4diac Type Export</li>
</ul>

<img src="../../html/4diacIDE/img/Step4/selectExportType.png" alt="Select Export Type" />

<p>Select the FBs to be exported on the right side of the wizard. 
It makes sense to use your own folder, we choose <i>ext_modules/EXAMPLE_TEST</i>.
Before exporting one or more Function Block Types, the Export Destination and the Exporter (FORTE 1.x) have to be chosen.
Furthermore, the version of the 4diac&nbsp;FORTE C++ format has to be selected. We'll export the three we just created.</p>
<p class="attention"><span class="inlineTitle">Attention:</span> Make sure that not all FBs are checked, otherwise all existing FBs will be exported!</p>

<img src="../../html/4diacIDE/img/Step4/export4DIACTypeWizard.png" alt="Export Type Wizard" />

<p>After clicking the button Finish and no warning pop up everything went fine. Your exported FBs are in the folder you chose before.
<br>If a dialog window pops up, something went wrong and it will inform you that the export to the 4diac&nbsp;FORTE C++ format was not successful.</p> 

<p>If the output directory already contains an older version of the exported Function Block Type, it is possible to overwrite the old file or to open a Merge Editor, where manual merges can be performed.</p>

<img src="../../html/4diacIDE/img/Step4/exportMergeWindow.png" width="1024" alt="Export Merge Window" />

<!--********************-->
<h3 id="finishService">Finish the Service Interface Test</h3>

<p>Now that you have exported the Service Interface Function Block, you need to edit it in order to get the desired behavior. 
Open the ServiceTest.cpp file that was recently exported, and take a look at the executeEvent function at the bottom.</p>

<div class="code">void FORTE_ServiceInterfaceTest::executeEvent(int pa_nEIID){
  switch(pa_nEIID){
    case scm_nEventREQID:
#error add code for REQ event!
/*
  do not forget to send output event, calling e.g.
      sendOutputEvent(scm_nEventCNFID);
*/
      break;
  }
}</div>

<p>The comment reminds us to set an output event, replace <i>#error add code for REQ event!</i> with <i>STATE() = !STATE();</i> for the toggling effect.</p>

<div class="code">void FORTE_ServiceTest::executeEvent(int pa_nEIID){
  switch(pa_nEIID){
    case scm_nEventREQID:
	  STATE() = !STATE();
	  sendOutputEvent(scm_nEventCNFID);
      break;
  }
}</div>

<p>To get or set an internal variable or data input in the 4diac&nbsp;FORTE template, you use the name and the parentheses. 
The sendOutputEvent is the specific function to send output events.</p>

<!--********************************************************************************************-->

<h2 id="OtherEditors">Other Type Editors</h2>
<p>Currently, only the management (i.e. creation, deletion and modification) of the Basic, Simple, Composite, Service Interface and Sub Application (SubApp) Function Block types as well as Adapter types are supported. 
The management of Device and Resource types is currently not supported.</p>

<!--********************************************************************************************-->

<h2 id="testFunctionBlock">Test Function Block</h2>

<p>The <b>FBTester tab</b> at the bottom of the central editing area is available for all Function Blocks. 
It allows testing the functionality of a Function Block by executing it on a target device. 
But first, 4diac&nbsp;FORTE must know about these FBs. 
So, you need to build 4diac&nbsp;FORTE using these Function Blocks just created. 
A guide to build your own 4diac&nbsp;FORTE is <a href="../../html/installation/install.html#ownFORTE">here</a>. 
See the section "Add external modules" on adding the files for compilation.</p>

<p>Once compiled, you can go to the FBTester, select 4diac&nbsp;FORTE Remote Tester in Test Configuration, and then set the IP and PORT for the 4diac&nbsp;FORTE that was compiled with the Function Blocks to be tested. 
The default is locally, but you can test them on any reachable 4diac&nbsp;FORTE.</p>

<p>Press Start Testing FB, and the FB will be loaded into 4diac&nbsp;FORTE, and you can manually set input values of your FB, trigger input events and inspect the resulting output events and output data. 
Furthermore. you can store input/output sequences and execute them to automatically test a certain functionality of your FB.</p>

<img src="../../html/4diacIDE/img/Step4/functionBlockTester.png" width="1024" alt="Functionblock Tester" />

<!--********************************************************************************************-->

<h1>Where to go from here?</h1>

<p>In the next step you will see other basic features</p>

<p><a href="../../html/4diacIDE/otherUseful.html">Step 5 - Other Basic Features</a></p>

<p>If you want to go back to the distributed application running remotely, here's a link</p>

<p><a href="../../html/4diacIDE/use4diacRemotely.html">Step 3 - Deploy Applications Remotely</a></p>

<p>If you want to go back to the Start Here page, we leave you here a fast access</p>

<p><a href="../../html/startHere/startHere.html">Where to Start</a></p>

<p class="goToTop"><a href="#topOfPage">Go to top</a></p>

</body>
</html>

